<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC
    "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
    "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
<html xmlns:svg='http://www.w3.org/2000/svg' xml:lang='en' xmlns='http://www.w3.org/1999/xhtml'>
<head><meta content='application/xhtml+xml;charset=utf-8' http-equiv='Content-type' /><title>Selenium Grid FAQ</title><link href='stylesheets/site.css' rel='stylesheet' type='text/css' />
<link href='stylesheets/document.css' rel='stylesheet' type='text/css' />
<link href='stylesheets/faq.css' rel='stylesheet' type='text/css' />
</head>
<body><div class='header'>
  <a href='index.html'><img src='images/selenium-grid-logo-large.png' alt='Selenium_grid_logo_large' /></a>
  <p>Configuring and Tuning</p>
</div>
<p class='toc'>Table Of Contents:</p>
<div class='maruku_toc'><ul style='list-style: none;'><li><a href='#selenium_grid_main_configuration_file'>Selenium Grid Main Configuration File</a></li><li><a href='#defining_new_environments'>Defining New Environments</a></li><li><a href='#changing_hubs_port'>Changing Hub&#8217;s Port</a></li><li><a href='#changing_hub_selfhealing_parameters'>Changing Hub Self-Healing Parameters</a></li><li><a href='#changing_remote_control_selfhealing_parameters'>Changing Remote Control Self-Healing Parameters</a></li><li><a href='#changing_maximum_wait_time_for_new_session'>Changing Maximum Wait Time for New Session</a></li></ul></div>
<h1 id='selenium_grid_main_configuration_file'>Selenium Grid Main Configuration File</h1>

<p>Once you have Selenium Grid up and running, you might want to tweak some of its settings.</p>

<p>Most of Selenium Grid configuration is defined in the <code>grid_configuration.yml</code> file located at the root of Selenium Grid installation directory <em>on the machine where the Hub is running</em>.</p>

<p>This file is in the human-friendly YAML format, which should be mostly self explanatory.</p>

<h1 id='defining_new_environments'>Defining New Environments</h1>

<p>Selenium Grid provides predefined environments for standard browsers to get you started, however, chances are that very soon, you will want to define your own.</p>

<p>To define a new environment, edit the <code>grid_configuration.yml</code> file located at the root of Selenium Grid installation directory <em>on the machine where the Hub is running</em>:</p>

<p>Search for a section like:</p>

<pre><code>hub:
   port: 4444
   # ...
   environments:
       - name:    &quot;Firefox on Windows&quot;
         browser: &quot;*firefox&quot;
       - name:    &quot;Firefox on OS X&quot;
         browser: &quot;*firefox&quot;
       - name:    &quot;IE on Windows&quot;
         browser: &quot;*iehta&quot;</code></pre>

<p>An environment is basically a binding between an arbitrary string you pick (the name) and a real Selenium browser string that will be used to start the session on the actual remote control (<code>*firefox</code>, <code>safari</code>, <code>*iexplore</code>, <code>*hta</code>, &#8230;). To add a new one, just add a new entry in the list, starting with a dash (<code>-</code>) and keeping the same indentation level. For instance, to add a new environment called &#8220;Shinny New Environment&#8221; that will use the <code>*safari</code> mode type:</p>

<pre><code>  hub:
     port: 4444
     # ...
     environments:
         - name:    &quot;Firefox on Windows&quot;
           browser: &quot;*firefox&quot;
         - name:    &quot;Firefox on OS X&quot;
           browser: &quot;*firefox&quot;
         - name:    &quot;IE on Windows&quot;
           browser: &quot;*iehta&quot;
         - name:    &quot;Shinny New Environment&quot;
           browser: &quot;*iehta&quot;</code></pre>

<h1 id='changing_hubs_port'>Changing Hub&#8217;s Port</h1>

<p>By default, Selenium Grid Hub is started on port 4444, which is also Selenium RC default port (this is on purpose, since, from the test&#8217;s point of view, the Hub looks just like a regular RC).</p>

<p>You can change the Hub port by editing the <code>grid_configuration.yml</code> file, which is located at the root of Selenium Grid installation directory <em>on the machine where the Hub is running</em>:</p>

<p>Search for a section like:</p>

<pre><code>hub:
   port: 4444	   </code></pre>

<p>And change <code>4444</code> to the port number of your liking. For instance:</p>

<pre><code>hub:
     port: 1234</code></pre>

<h1 id='changing_hub_selfhealing_parameters'>Changing Hub Self-Healing Parameters</h1>

<p><code>remoteControlPollingIntervalInSeconds</code> and <code>sessionMaxIdleTimeInSeconds</code> configuration parameters can be set in <code>grid_configuration.yml</code>. For instance:</p>

<pre><code> hub:
    port: 4444
    remoteControlPollingIntervalInSeconds: 180
    sessionMaxIdleTimeInSeconds: 300
    environments:
        - name:    &quot;Firefox on Windows&quot;
          browser: &quot;*firefox&quot;</code></pre>

<ul>
<li>
<p><code>remoteControlPollingIntervalInSeconds</code> : is how often the Hub will check for registered Remote Controls status and idle testing sessions.</p>
</li>

<li>
<p><code>sessionMaxIdleTimeInSeconds</code> : is how long a testing session can be idle before the Hub automatically unregisters the associated Remote Control.</p>
</li>
</ul>

<h1 id='changing_remote_control_selfhealing_parameters'>Changing Remote Control Self-Healing Parameters</h1>

<p>When starting the Remote Control you can set <code>hubPollerIntervalInSeconds</code> to control how often the Remote Controls will check the Hub status and automatically re-register themselves in case the Hub does not list them as registered.</p>

<p>e.g.</p>

<pre><code>ant -DhubPollerIntervalInSeconds=120 launch-hub  </code></pre>

<h1 id='changing_maximum_wait_time_for_new_session'>Changing Maximum Wait Time for New Session</h1>

<p>By default the Hub will block until a Remote Control becomes available when requesting a new browser session. This can be problematic if the requesting client times out. Since the Hub is unaware of this timeout, it will request the new session anyway and that session will become effectively orphaned.</p>

<p>If your client cannot wait for the session you may change the maximum time the Hub will wait in <code>grid_configuration.yml</code>. When the <code>newSessionMaxWaitTimeInSeconds</code> value is exceeded, the Hub will return an Error indicating that no Remote Controls were available to fulfill the request.</p>

<p>For instance:</p>

<pre><code>  hub:
     newSessionMaxWaitTimeInSeconds: 120</code></pre>

<p>This sample configuration will instruct the Hub to block for up to 2 minutes while waiting for a Remote Control to become available to handle the new session request.</p>

<p><em>NB: If this configuration value is not provided, the default value of infinite will be used.</em></p>
</body></html>
